

>>>>>>>>>>>>>>  CoolCV user's manual  <<<<<<<<<<<<<<<<

                 by Oscar Toledo G.
       (c) Copyright 2015-2020 Oscar Toledo G.
                http://nanochess.org/
               E-mail: biyubi@gmail.com

First developed: Jul/22/2015
Last revision: Sep/02/2020


>>>>>>>>>>>>>>  Legal notice

This software is provided 'as-is', without any express or implied warranty. 
In no event will the author be held liable for any damages or loss arising 
from the use of this software.

It is prohibited to modify, decompile, disassemble or reverse engineer this 
software.

All trademarks are property of their respective owners.

Integrates Simple DirectMedia Layer http://www.libsdl.org


>>>>>>>>>>>>>>  Changes in this version

v0.6.9 Sep/02/2020  o Allows to take screenshots while paused.

v0.6.8 Jun/16/2020  o Allows to reverse direction of joystick for
                      interpretation of left/right and up/down.

v0.6.7 Jun/13/2020  o Added trash in memory for RAND_GEN in Coleco BIOS.
                    o Pausing the emulator doesn't show trash in window.
                    o Messages shown on pausing.
                    o Now >really< including libSDL inside the package.

v0.6.6 Nov/30/2017  o Added Ctrl+Fn+F4 to save a memory snapshot.
                    o Added Ctrl+Fn+F9 to allow logging PSG state.

v0.6.5 May/25/2017  o Corrected bug where Sammy Lightfoot would get stuck
                      after title screen.
                    o Adjusted timings for several Z80 instructions.
                    o Added VDP 4K mapper emulation.
                    o Added VDP register access in range 0xc000-0xffff.
                    o Added undocumented VDP modes, now covered all
                      combinations of mode setting (R0 1 bit + R1 2 bits)
                    o Windows version now can switch to full screen using
                      Alt + Enter.
                    o Mac OS X version now have shortcut Cmd + Ctrl + F
                      to switch to full screen.
                    o Allows to configure joysticks for controllers.
                    o Saves full screen state (when used with shortcut)

v0.6.4 Feb/15/2016  o Now ADAM keyboard is fully configurable.

v0.6.3 Jan/11/2016  o Enhanced Z80 emulation, the emulator ran too fast.
                      (reported by Armando Perez). This solves the pitch
                      in synthetized voice in Sewer Sam and Squish'Em.
                    o Keys F4 and F7 are now configurable.
                    o Expertype and ADAM Bomb 2 now are working.
                    o Fixed some keys for ADAM in Windows version.
                    o Added 64K RAM expansion for ADAM.
                    o Fixed bug in joystick support. (still untested)

v0.6.2 Nov/27/2015  o Enhanced Z80 emulation for special interruption cases.
                    o Enhanced VDP emulation for special collision case.
                    o New Ctrl+Fn+F4 to create debugging snapshots
                      (experimental), these go into your Documents folder or
                      your home directory.
                    o Support to use two keys in mapping to activate one button
                      or action.
                    o Support to use two independent keys to activate same button
                      or action.
                    o Raspberry now shows status messages (including the key
                      codes show by F7)
                    o More keys are configurable: video recording, audio
                      recording, screenshots, enable/disable roller controller.
                    o When using Roller Controller now sensitivity has been
                      adjusted.

v0.6.1 Nov/05/2015  o Pause and Reset key couldn't use joystick.
                    o Better compression for AVI and safeguard if 2GB limit
                      is reached.
                    o PAL switching didn't update BIOS European byte.
                    o Able to exit using # and * key at same time (only
                      Raspberry)

v0.6.0 Nov/04/2015  o Added fast startup of Colecovision BIOS.
                    o Roller controller enabled/disabled with only fn-F5.
                    o Video recording, pressing fn-F6 to start/stop. You
                      can playback the video using VLC Player.
                    o Support for right Shift + Enter exit on Raspberry PI.
                    o All versions of CoolCV updated (Mac, Windows, Linux
                      and Raspberry PI)

v0.5.5 Oct/14/2015  o Added configurable Pause key (fn-F3)
                    o Added configurable Reset key (<- Backspace)
                    o Changed NTSC/PAL switch to fn-F4

v0.5.4 Sep/23/2015  o Added Super Action Controller support. (buttons 3
                      and 4 not configured, you need to edit mapping)
                    o The key mappings are taken from the file
                      Documents/coolcv_mapping.txt created when you
                      run the emulator for the first time. (check Fn+F7)

v0.5.3 Sep/01/2015  o Allows to save screenshots in PNG using Fn+F10
                      It goes to your Pictures folder.
                    o Now you can feed it with ZIP files containing the
                      Colecovision game ROM.

v0.5.2 Aug/31/2015  o Allows to record audio using Fn+F9.
                      It goes to your Music folder.

v0.5.1 Aug/25/2015  o Now it can run in Raspberry Pi (highly experimental)
                    o See below for notes on running it.

v0.5.1 Aug/08/2015  o Solved bug in collision bit of VDP
                    o Deactivates SGM while running Super Donkey Kong
                      prototype of 1983 (caused crash)
                    o Now controllers should feel smoother.

v0.5   Aug/01/2015  o Compiled for Windows/Linux.

v0.5   Jul/31/2015  o Experimental support for Coleco ADAM.

v0.4   Jul/30/2015  o Compiled for Windows/Linux.

v0.4   Jul/29/2015  o Support for controller 2 in keyboard.
                    o Changed * and # keys in keyboard for controller 1.
                    o Added support for up to 2 joysticks (not tested)
                    o Higher output volume.
                    o Press Fn+F7 to switch joystick buttons.
                    o Now configure your ROM files using context menu and
                      Get Info, change application to CoolCV and make
                      change for all. Now a double click in your ROM file
                      will open the ROM with CoolCV :)

v0.3   Jul/25/2015  o Compiled for Windows (in this platform the ROM file
                      must be dropped over main window)

v0.3   Jul/24/2015  o Now Mac OS X app, run it.
                    o To load ROM files drag and drop over the CoolCV icon
                      in the task bar while running.
                    o As there is no command line, -sgm option is always
                      active.
                    o Now libsdl2 is integrated.
                    o Now coleco.rom is integrated.
                    o Experimental support for Roller Controller.
                    o Show current ROM in title bar.

v0.2   Jul/23/2015  o Allows window resizing and full screen.
                    o Slightly higher output volume.
                    o New option -pal for PAL VDP (also patches BIOS)
                    o Support for snapshots.

v0.1   Jul/22/2015   First release


>>>>>>>>>>>>>>  Description

This is a Colecovision/Sega SG1000 emulator for Mac OS X 10.9.6 or higher.
Universal binary included.

I've included princess_quest.rom (my now freely released Princess Quest game)
and super_game_module_test.rom for testing the SGM support.

Go to finder and open application CoolCV with context menu.

Once running, drag and drop ROM files over the CoolCV icon in the task bar
at the bottom of screen.

It can run any Colecovision cart, including Megacart ones. Opcode Super
Game Module support is always enabled.

Controller 1 supported, default mapping is:

   Arrow keys = directions
   Space = Left button
   M = Right button

   0-9 = Keypad buttons
   O = Asterisk key
   P = # key
   
Controller 2 supported, default mapping is:

   W-A-S-D = directions
   Tab = Left button
   Q = Right button
   
   R T Y  =  1 2 3
   F G H  =  4 5 6
   V B N  =  7 8 9
   J K L  =  * 0 #

Press Fn-F1 to save snapshot (saved in /var/tmp/coolcv_snapshot.bin)

Press Fn-F2 to restore snapshot.

Press Fn-F3 to pause emulator.

Press Fn-F4 to switch between NTSC and PAL (forces reset).
               If you press Ctrl along it (not configurable) then it will
               create a memory snapshot in your Documents folder.

Press Fn-F5 to enable/disable Roller Controller support.

Press Fn-F6 to record a video (AVI with ZMBV codec, put in your Movies folder
               My Documents folder in Windows, or home directory in others)
               This video can be uploaded directly to Youtube. ;)

Press Fn-F7 to enable/disable information of keys/joystick for configuration.

Press Fn-F8 to switch speed of ADAM tape/disk between normal and ultrafast.

Press Fn-F9 to record audio (WAV files are put in your Music folder, My
               Music folder in Windows, or home directory in others).
               If you press Ctrl along it (not configurable) then it will
               start logging PSG state in each video frame. (at your
               documents folder).

Press Fn-F10 to save a screenshot (PNG files are put in your Pictures folder,
                My Pictures folder in Window, or home directory in others).

Press Backspace <- to force reset. If you are using the Coleco ADAM mode
then probably you'll want to remap this.

Cmd+Ctrl+F switches full screen.

Cmd+Q exits emulator.


PLATFORM DEPENDANT:

Windows - Press Alt + Enter to toggle full screen.

Most keys are configurable, check below.

Note that if you're recording a video there could be a chance that the
emulator gets slow or sound cuts, don't worry, your video will come out
perfect. Also AVI file will be automatically stopped once it reachs
2 GB size.


>>>>>>>>>>>>>>  Controller mappings edit

Press Fn-F7 to show the codes for each key or joystick button when pressed,
these can be used to change Documents/coolcv_mappings.txt using TextEdit

This file is created automatically the FIRST TIME when CoolCV is run.

Note each controller key/direction can use both a key and a joystick button.

You can put both in same line, for example.

    left_button_1	key32	joy0_0
    
The names key32 and joy0_0 are these reported by Fn+F7.

You can put another key## and joy#_# in same line, so CoolCV will wait for
these two keys to be pressed or joystick buttons to be pressed, for example:

    left_button_1	key32	key97  joy0_0 joy0_1

It will make to activate left button 1 using Spacebar plus A key, or using
joystick 0 button 0 plus button 1.

Also you can add another line to indicate more keys/joystick to activate a
button, for example:

    left_button_1	key32
    left_button_1	key97
    
It will make left button to be activated using Spacebar or A key.

You can also configure the joysticks this way, the lines are:
 
    joystick_1_vert
    joystick_1_horiz
    joystick_2_vert
    joystick_2_horiz

Move your joystick while using the show codes function to see what
joystick and axis codes you want to use for each controller.

Also in the same line there is a "neg" setup so you can reverse
direction putting it to 1 (for example, when your joystick has
different sign in input for up/down).


>>>>>>>>>>>>>>  Notes for Coleco ADAM support (experimental)

Press Fn-F8 to enable/disable fast disk/tape loading.

To load a disk or tape simply drop it in the icon in task bar (Mac),
note it will reset the machine immediately to run it. Disks should
have extension .dsk and tapes should have extension .ddp

Please note also the file will be open with writing permissions, so be
sure to make a backup if you don't want it to be changed (score tables
in games and so)

The keyboard mapping is for Mac OS X with US keyboard, in my tests with
Spanish mapping I've been unable to decode certain keys.

Special keys:

    Alt + W = Wild card
    Alt + U = Undo
    Alt + M = Move
    Alt + S = Store
    Alt + I = Insert
    Alt + P = Print
    Alt + C = Clear
    Alt + D = Delete

    Alt + H = Home
    Alt + 1 = I
    Alt + 2 = II
    Alt + 3 = III
    Alt + 4 = IV
    Alt + 5 = V
    Alt + 6 = VI
    
Appears to work just fine with SmartBASIC v1.2 and several games.

The mappings can be changed, only make sure the "complicated" keys come
first as these will be searched first. For example:

    adam_shift_wildcard	shift	alt	key119
    adam_wildcard	alt	key119

The adam_shift_wildcard (shift alt y) should come before than
adam_wildcard (alt y)

Note that only the ADAM keys allow the 'shift', 'ctrl' and 'alt' keywords,
these are not taken in account for Colecovision controllers or emulation
actions.


>>>>>>>>>>>>>>  Running over Linux

For some reason libsdl isn't compatible with some audio outputs, try changing
from ALSA to OSSv4 in Ubuntu.


>>>>>>>>>>>>>>  Running over Raspberry PI

Running it over Retropie 2.6 and further is easy as it includes libSDL2
pre-built. Just change permissions to executable and run. (thanks to
intvdave for checking it)

Unfortunately there is no available build of libSDL2 for Raspbian, you
should install it using the Terminal: (this can take over a hour!)

    sudo apt-get update
    sudo apt-get upgrade
    sudo rpi-update
    sudo apt-get install build-essential libfreeimage-dev libopenal-dev libpango1.0-dev libsndfile-dev libudev-dev libasound2-dev libjpeg8-dev libtiff5-dev libwebp-dev automake
    cd ~
    wget https://www.libsdl.org/release/SDL2-2.0.3.tar.gz
    tar zxvf SDL2-2.0.3.tar.gz
    cd SDL2-2.0.3 && mkdir build && cd build
    ../configure --disable-pulseaudio --disable-esd --disable-video-mir --disable-video-wayland --disable-video-x11 --disable-video-opengl --host=armv7l-raspberry-linux-gnueabihf
    make -j 4
    sudo make install

Once it's ready you should close your terminal window and run CoolCV
using the Run menu option (otherwise the terminal shows weird chars
and makes slow the emulation)

    /home/pi/coolcv_pi /home/pi/quest.rom

Supposing you unzipped it in your default home directory.

It always run at full screen, so you should quit before running another
game.

To quit use Ctrl+Esc, Right Shift + Enter (Retropie) or Alt+F4.

UNDER YOUR OWN RISK: It's suggested to overclock your Raspberry PI to
800 mhz, 700 isn't enough and fortunately 800 mhz doesn't require
overvoltage. You can do it using:

    sudo raspi-config
    
    
>>>>>>>>>>>>>>  Installing in Retropie

Groovy978 from Atariage gives the following suggestions:

  If you want integred coolcv to retropie you need first copy your coolcv
  at cd /opt/retropie/emulators/coolcv and add this lines at
  nano /etc/emulationstation/es_systems.cfg:

  <system>
    <name>colecovision</name>
    <fullname>ColecoVision</fullname>
    <path>~/RetroPie/roms/colecovision</path>
    <extension>.rom .ROM .col .COL</extension>
    <command>/opt/retropie/emulators/coolcv/coolcv_pi %ROM% </command>
    <platform>colecovision</platform>
    <theme>colecovision</theme>
  </system>

  And don't forget this line finish with:</systemList>

  This way work great for coolcv on retropie

  keyboard works

  joystick works.

  Good pleasure!


>>>>>>>>>>>>>>  Mac OS X Catalina

ColecoJoe contributes this tip to make CoolCV to work in Mac OS X Catalina.

Run this using Terminal (change Path-To):

  sudo xattr -d com.apple.quarantine Path-To/CoolCV.app


>>>>>>>>>>>>>>  Supporting the developer

If you find CoolCV useful, please show your appreciation making a donation
via Paypal ($9 USD suggested) to b-i+y-u+b-i (at) gmail.com

If you find a bug, please report to same email and I'll try to look into
it. Because lack of time I cannot guarantee it will be corrected.

Also you can buy my book "Colecovision Games Guide", including reviews,
screenshots, and score table for all of the games released during the
Colecovision commercial availability. Including a foreword by Jennell
Jaquays, former game design manager at Coleco.

  Black&White version, paperback.

    https://www.lulu.com/shop/oscar-toledo-gutierrez/colecovision-games-guide/paperback/product-1vgk9req.html

  Color version, paperback.

    https://www.lulu.com/shop/oscar-toledo-gutierrez/colecovision-games-guide-color-edition/paperback/product-24179549.html

